home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1996 April / MacFormat CD Edition MF36 (April 1996).iso / Shareware City / Developers / Tools Plus - GUI⁄Event libs / Tools Plus 2.6.1a Evaluat'n Kit / Tools Plus 2.6.1a / User Manual / 07-Picture Buttons (2 of 3) < prev    next >
INI File  |  1994-09-17  |  27KB  |  426 lines
  1. [Display using Monaco 9]
  2.  
  3.  
  4. Behavior and Appearance Specification
  5. `````````````````````````````````````
  6.   ProcID specifies the picture button’s appearance and behavior characteristics.  It is used by the button to determine its behavioral characteristics, and how it looks when selected or deselected, enabled or disabled, and when the button’s value is changed.  The value for this 4-byte long integer can be specified either by adding a set of constants to obtain the desired result, or using a specially defined variant record, as illustrated below:
  7.  
  8. picbutInstantEvent         Report a picture button event as soon as the
  9.                            mouse-down occurs in the button.  This option
  10.                            is best utilized with “click sensitive”
  11.                            icons, such as the ones seen in the Chooser.
  12.                            Instant events are automatically turned on
  13.                            when you turn on the “repeating events”
  14.                            option.
  15.  
  16. picbutTrackWithHilite      Draw a tracking highlight (a bold outline
  17.                            around the button, similar to the one used by
  18.                            the toolbox’s radio buttons) when the mouse
  19.                            button is down and its cursor is inside the
  20.                            button’s area.
  21.  
  22. picbutLockSelected         When the user selects the button, lock it in
  23.                            the selected state thereby disallowing the
  24.                            user to deselect it.  This option is usually
  25.                            used to produce the functionality of radio
  26.                            buttons, where a button can be turned on by
  27.                            clicking on it, but the user has to click
  28.                            another button to turn this one off.  If you
  29.                            turn on this option, the “switch selected”
  30.                            and “repeating events” options are
  31.                            automatically turned off.
  32.  
  33. picbutSwitchSelected       When the user clicks the button, reverse the
  34.                            “selection” state (i.e., if currently
  35.                            selected, switch to deselected.  If currently
  36.                            deselected, switch to selected).  This option
  37.                            produces a simple click-on/click-off type of
  38.                            button using a single stage.  If you turn on
  39.                            this option, the “lock selected” and
  40.                            “repeating events” options are automatically
  41.                            turned off.
  42.  
  43. picbutRepeatEvents         Repeated doPictButton events are produced as
  44.                            long as the mouse button is down and its
  45.                            cursor is inside the button’s area.  These
  46.                            events can optionally increment/decrement the
  47.                            button’s value at a specified rate.  This
  48.                            option is useful for button’s that control
  49.                            movement of objects, or situations where the
  50.                            button’s value may change by more than one.
  51.                            If you turn on this option, the “instant
  52.                            events” option is automatically turned off.
  53.  
  54. picbutAutoValueChg         Automatically increment/decrement the
  55.                            button’s value when it is selected by the
  56.                            user.  If this option is not used, your
  57.                            application must manually change button
  58.                            values where applicable.  Automatic value
  59.                            changing is only useful if your button has a
  60.                            range of values through which is can
  61.                            progress.
  62.  
  63. picbutScaleLinear          This option controls the speed of automatic
  64.                            value changes when the “repeat events” option
  65.                            is turned on.  After an initial pause, the
  66.                            button’s value will increment/decrement at a
  67.                            fixed rate.  This option can only be used in
  68.                            conjunction with the “automatic value change”
  69.                            option.  You may specify only one of the four
  70.                            possible rates for automatic value changes:
  71.                            Linear (default), slow acceleration, medium
  72.                            acceleration, or fast acceleration.
  73.  
  74. picbutScaleSlowAccel       Same as above, but the rate accelerates
  75.                            slowly.
  76.  
  77. picbutScaleMedAccel        Same as above, but the rate accelerates at a
  78.                            moderate rate.
  79.  
  80. picbutScaleFastAccel       Same as above, but the rate accelerates
  81.                            rapidly.
  82.  
  83. picbutValueWrap            When a button’s value reaches either the high
  84.                            or low limit, start at the opposite end of
  85.                            the range.  This option can only be used in
  86.                            conjunction with the “automatic value change”
  87.                            option.  
  88.  
  89. picbutLeftRightSplit       Clicking on the left half of the button
  90.                            decrements the button’s value, while clicking
  91.                            on the right half increments it.  You cannot
  92.                            combine this option with the top/bottom
  93.                            split.
  94.  
  95. picbutTopBottomSplit       Clicking on the bottom half of the button
  96.                            decrements the button’s value, while clicking
  97.                            on the top half increments it.  If you turn
  98.                            on this option, the “left/right split” option
  99.                            is automatically turned off.
  100.  
  101. picbutMultiStage           The button has a different image for each of
  102.                            its possible values.  Note that even with
  103.                            this option turned off, you may still decide
  104.                            to use an alternate image for a selected
  105.                            button and/or a disabled button.
  106.  
  107. picbutBigSICN3D            If you are using an SICN icon to produce a 3D
  108.                            button, you can create a slightly larger
  109.                            button (24 x 22 pixels) with more pronounced
  110.                            shading.  Without this option, SICN icons
  111.                            produce a slightly smaller button (24 x 20
  112.                            pixels).
  113.  
  114. picbutUsePICTS             Use PICTs instead of icons for the button’s
  115.                            image(s).  Note that PICTs and icons use
  116.                            different resource numbering schemes.  See
  117.                            the relevant details earlier in this chapter.
  118.  
  119. picbutGray4use8            If your 8-bit PICTs look good on 4-bit gray
  120.                            scale monitors, turn this option on to allow
  121.                            them to be used in such a way.  Otherwise, a
  122.                            4-bit PICT is required when a monitor is
  123.                            set to 4-bits.  This option can only be used
  124.                            in conjunction with the “use PICTs” option.
  125.  
  126. Selection Effects (Choose only one)…
  127.  
  128. picbutSelectDarken         Darken the button’s image when it is
  129.                            selected.
  130.  
  131. picbutSelectDarkenSICN3D   Darken and “push in” a 3D button when it is
  132.                            selected.  An SICN resource is used for the
  133.                            button’s image.  Tools Plus converts the SICN
  134.                            to a 3D color button, and formulates all the
  135.                            necessary selected and disabled images.
  136.  
  137. picbutSelectLightenSICN3D  Lighten and “push in” a 3D button when it is
  138.                            selected.  An SICN resource is used for the
  139.                            button’s image.  Tools Plus converts the SICN
  140.                            to a 3D color button, and formulates all the
  141.                            necessary selected and disabled images.
  142.  
  143. picbutSelectPushedSICN3D   “Push in” a 3D button when it is selected,
  144.                            but don’t darken or lighten the button.  An
  145.                            SICN resource is used for the button’s image.
  146.                            Tools Plus converts the SICN to a 3D color
  147.                            button, and formulates all the necessary
  148.                            selected and disabled images.  This option is
  149.                            suitable for momentary push buttons (like the
  150.                            Macintosh’s standard push button), because
  151.                            they provide little visual feedback that the
  152.                            button is selected.
  153.  
  154. picbutSelectAltImage       Use an alternate image when the button is
  155.                            selected.  If the button is multistage, a
  156.                            selected image will likely be required for
  157.                            each stage.
  158.  
  159. Disabling Effects (Choose only one)…
  160.  
  161. If a disabling effect is not specified, the global default is used as defined by the DefaultIconLook routine.
  162.  
  163. picbutDimUsingBlackLite    When the button is disabled, overlay the
  164.                            image with a black color using a “light gray”
  165.                            (25%) pattern.
  166.  
  167. picbutDimUsingWhiteLite    When the button is disabled, overlay the
  168.                            image with a white color using a “light gray”
  169.                            (25%) pattern.
  170.  
  171. picbutDimUsingWhite        When the button is disabled, overlay the
  172.                            image with a white color using a “medium
  173.                            gray” (50%) pattern.
  174.  
  175. picbutDimLeaveBorder       When the button is disabled, do not apply the
  176.                            disabling effect to the image’s border.  This
  177.                            option can be used in conjunction with any of
  178.                            the disabling effects listed above.
  179.  
  180. picbutDimAltImage          Use an alternate image when the button is
  181.                            disabled.  If the button is multistage, a
  182.                            selected image will likely be required for
  183.                            each stage.  You may have to create a
  184.                            disabled image for both the selected and
  185.                            deselected state if the button can be seen in
  186.                            such a way.
  187.  
  188. picbutDimNoChange          The button appears unchanged when it is
  189.                            disabled.  The user is beeped if they click
  190.                            on a disabled button.
  191.  
  192.   So, if you want to create a large SICN 3D picture button that locks into the selected state, lightens when selected, and is disabled by overlaying the image using a white color with a 50% gray pattern, you should use the combined constants picbutLockSelected + picbutBigSICN3D + picbutSelectLightenSICN3D + picbutDimUsingWhite.  Alternatively, a C structure and a Pascal variant record are available to help you define the ProcID in a more intuitive way, as shown below:
  193.  
  194.  
  195. union TPPictButtonSpec {       /*Picture Button's appearance and      */
  196.                                /*  behavior specs in 2 formats…       */
  197.   struct{                      /* • Parsed into components:           */
  198.     unsigned short InstantEvent: 1;    /*  Report event on mouse-down */
  199.     unsigned short TrackWithHilite: 1; /*  Track using hilighting     */
  200.                                        /*    (like a radio button)    */
  201.     unsigned short LockSelected: 1;    /*  Lock if selected (mouse    */
  202.                                        /*    can't deselect)          */
  203.     unsigned short SwitchSelected: 1;  /*  Switch 'select' state if   */
  204.                                        /*    clicked.                 */
  205.     unsigned short RepeatEvents: 1;    /*  Repeat event when button is*/
  206.                                        /*    held.                    */
  207.     unsigned short AutoValueChg: 1;    /*  Automatically chg button's */
  208.                                        /*    value.                   */
  209.     unsigned short AutoValueScaling: 3;/*  Rate of change for button's*/
  210.                                        /*    value.                   */
  211.     unsigned short ValueWrap: 1;       /*  Button's range of values   */
  212.                                        /*    'wrap' around.           */
  213.     unsigned short LeftRightSplit: 1;  /*  Left side reduces value,   */
  214.                                        /*    right increase.          */
  215.     unsigned short TopBottomSplit: 1;  /*  Top increases value, bottom*/
  216.                                        /*    reduces.                 */
  217.     unsigned short MultiStage: 1;      /*  Button has multiple stages */
  218.     unsigned short BigSICN3D: 1;       /*  Make SICN 3D button larger */
  219.     unsigned short UsePICTS: 1;        /*  Use PICTs instead of icons */
  220.     unsigned short Gray4use8: 1;       /*  Use 8-bit color pict on    */
  221.                                        /*    4-bit gray scale monitor.*/
  222.                                        /*Selection Effects…           */
  223.     unsigned short SelectDarken: 1;       /*   Darken image           */
  224.     unsigned short SelectDarkenSICN3D: 1; /*   Darken (+push in) a 3D */
  225.                                           /*     SICN icon.           */
  226.     unsigned short SelectLightenSICN3D: 1;/*   Lighten (+push in) 3D  */
  227.                                           /*     SICN icon.           */
  228.     unsigned short SelectPushedSICN3D: 1; /*   Same color (+push) 3D  */
  229.                                           /*     SICN icon.           */
  230.     unsigned short bit19: 1;              /*   (reserved bit)         */
  231.     unsigned short bit20: 1;              /*   (reserved bit)         */
  232.     unsigned short SelectAltImage: 1;     /*   Use an alternate image */
  233.     unsigned short bit22: 1;              /*   (reserved bit)         */
  234.                                         /*Disabling Effects…          */
  235.     unsigned short DimUsingBlackLite: 1;/*  Overlay Black color, Lt   */
  236.                                         /*    Gray pattern.           */
  237.     unsigned short DimUsingWhiteLite: 1;/*  Overlay White color, Lt   */
  238.                                         /*    Gray pattern.           */
  239.     unsigned short DimUsingWhite: 1;    /*  Overlay White color, Gray */
  240.                                         /*    pattern.                */
  241.     unsigned short bit26: 1;            /*  (reserved bit)            */
  242.     unsigned short bit27: 1;            /*  (reserved bit)            */
  243.     unsigned short DimLeaveBorder: 1;   /*  Leave border when effect  */
  244.                                         /*    applied.                */
  245.     unsigned short DimAltImage: 1;      /*  Use an alternate image    */
  246.     unsigned short DimNoChange: 1;      /*  Button looks same when    */
  247.                                         /*    disabled.               */
  248.     unsigned short bit31: 1;            /*  (reserved bit)            */
  249.    } Bits;                              /*                            */
  250.    long Num;                            /* • Long equivalent          */
  251. };                                      /*                            */
  252. typedef union TPPictButtonSpec TPPictButtonSpec;
  253.  
  254.  
  255.  
  256.  
  257. TPPictButtonSpec = packed record {Picture Button's appearance &behavior}
  258.                                  {  specifications in 2 formats…       }
  259.   case integer of                {                                     }
  260.     0: (                             { • Parsed into components:       }
  261.       InstantEvent: boolean;         {     Report event on mouse-down  }
  262.       TrackWithHilite: boolean;      {     Track using hilighting, like}
  263.                                      {       a radio button.           }
  264.       LockSelected: boolean;         {     Lock if selected (mouse     }
  265.                                      {       can't deselect)           }
  266.       SwitchSelected: boolean;       {     Switch 'selected' state if  }
  267.                                      {       clicked                   }
  268.       RepeatEvents: boolean;         {     Repeat event when button is }
  269.                                      {       held down                 }
  270.       AutoValueChg: boolean;         {     Automatically change        }
  271.                                      {       button's value            }
  272.       AutoValueScaling: 0..3;        {     Rate of change for button's }
  273.                                      {       value.                    }
  274.       ValueWrap: boolean;            {     Button's range of values    }
  275.                                      {       'wrap' around             }
  276.       LeftRightSplit: boolean;       {     Left side reduces value,    }
  277.                                      {       right increases.          }
  278.       TopBottomSplit: boolean;       {     Top increases value, bottom }
  279.                                      {       reduces.                  }
  280.       MultiStage: boolean;           {     Button has multiple stages  }
  281.       BigSICN3D: boolean;            {     Create a larger SICN 3D     }
  282.                                      {       button                    }
  283.       UsePICTS: boolean;             {     Use PICTs instead of icons  }
  284.       Gray4use8: boolean;            {     Use 8-bit color pict on     }
  285.                                      {       4-bit gray monitor        }
  286.                                      {Selection Effects…               }
  287.       SelectDarken: boolean;         {     Darken image                }
  288.       SelectDarkenSICN3D: boolean;   {     Darken (and push in) a 3D   }
  289.                                      {       SICN icon.                }
  290.       SelectLightenSICN3D: boolean;  {     Lighten (and push in) a 3D  }
  291.                                      {       SICN icon.                }
  292.       SelectPushedSICN3D: boolean;   {     Same color (and push in) a  }
  293.                                      {       3D SICN icon.             }
  294.       bit19, bit20: boolean;         {      (reserved bits)            }
  295.       SelectAltImage: boolean;       {     Use an alternate image      }
  296.       bit22: boolean;                {      (reserved bit)             }
  297.                                      {Disabling Effects…               }
  298.       DimUsingBlackLite: boolean;    {     Overlay Black color using Lt}
  299.                                      {       Gray pattern              }
  300.       DimUsingWhiteLite: boolean;    {     Overlay White color using Lt}
  301.                                      {       Gray pattern              }
  302.       DimUsingWhite: boolean;        {     Overlay White color using   }
  303.                                      {       Gray pattern              }
  304.       bit26, bit27: boolean;         {      (reserved bits)            }
  305.       DimLeaveBorder: boolean;       {     Leave border when applying  }
  306.                                      {       effect.                   }
  307.       DimAltImage: boolean;          {     Use an alternate image      }
  308.       DimNoChange: boolean;          {     Button looks the same when  }
  309.                                      {       disabled.                 }
  310.        bit31: boolean;               {     (reserved bit)              }
  311.      );                              {                                 }
  312.      1: (                            {• Longint equivalent:            }
  313.        Num: longint;                 {     Specification longint       }
  314.      );                              {                                 }
  315.    end;
  316.  
  317.  
  318.  
  319.   As an example, lets create a picture button that repeats events, uses an alternate image when selected, and looks the same when disabled.  The following code sample illustrates how this is done:
  320.  
  321. procedure DoItNow;
  322.   var
  323.     ProcID: TPPictButtonSpec; {Define the variable used for the ProcID}
  324.   begin
  325.     ProcID.Num := 0;          {Initialize all the bits to zero values }
  326.     ProcID.RepeatEvents := true; {Button will produce repeating events}
  327.     ProcID.SelectAltImage := true;{Alternate image is used when button}
  328.                                   {  is selected.                     }
  329.     ProcID.DimNoChange:= true;    {Button looks the same when disabled}
  330.                                   {Create the picture button using the}
  331.                                   {  long integer part of the ProcID… }
  332.     NewPictButton(1, 441, 5, PlusIcon, ProcID.Num, enabled, notSelected,
  333.                         0, 0, 0); {                                   }
  334.  
  335.  
  336.   You can use whatever you like best as the ProcID, a single constant, several constants added together, a variable, or the long integer component of a structure or variant record.
  337.  
  338.  
  339.  
  340. Rate of Repeating Events
  341. ````````````````````````
  342.   Picture buttons have the ability to produce repeating events when they are held down.  Four predefined rates are available to control the speed at which a picture button’s value changes:
  343.  
  344.   • Linear:             The button’s value changes when the button is
  345.                         selected.  After a brief pause, the value
  346.                         continues to change at a slow and consistent
  347.                         rate.
  348.  
  349.  • Slow Acceleration:   The button’s value changes when the button is
  350.                         selected.  After a brief pause, the value
  351.                         continues to change at a rate that slowly
  352.                         accelerates.
  353.  
  354.  • Medium Acceleration: The button’s value changes when the button is
  355.                         selected.  After a brief pause, the value
  356.                         continues to change at a moderately accelerating
  357.                         rate.
  358.  
  359.  • Fast Acceleration:   The button’s value changes when the button is
  360.                         selected.  After a brief pause, the value
  361.                         continues to change at a rate that rapidly
  362.                         accelerates.
  363.  
  364.   There is yet another way to control a button’s speed, and that is by using the SetPictButtonSpeed procedure which lets you specify an exact rate (change in value per second).  When you use SetPictButtonSpeed, the specified rate takes effect immediately when the user presses the picture button.  Unlike the four standard Tools Plus acceleration rates, there is no pause between the time when the user selects the picture button and when the repeating events begin.
  365.  
  366. Note: If your application calls PollSystem more often than the picture
  367.       button’s rate of change, your application will receive doNothing
  368.       events (no event).  This produces no ill effects, but you should
  369.       be aware that it is possible to receive doNothing events between
  370.       doPictButton events.
  371.  
  372.   CONST                   {Pict Button Behavior and Appearance Specs:  }
  373.     picbutInstantEvent   = $80000000; { Report event on mouse-down     }
  374.     picbutTrackWithHilite= $40000000; { Track using hiliting, like a   }
  375.                                       {   radio button.                }
  376.     picbutLockSelected   = $20000000; { Lock if selected (mouse can't  }
  377.                                       {   deselect)                    }
  378.     picbutSwitchSelected = $10000000; { Switch 'selected' state if     }
  379.                                       {   clicked.                     }
  380.     picbutRepeatEvents   = $08000000; { Repeat event when button is    }
  381.                                       {   held down.                   }
  382.     picbutAutoValueChg   = $04000000; { Automatically change button's  }
  383.                                       {   value.                       }
  384.     picbutScaleLinear    = $00000000; { Rate of automatic value change…}
  385.     picbutScaleSlowAccel = $01000000; {    Linear, Slow Acceleration,  }
  386.     picbutScaleMedAccel  = $02000000; {    Medium Acceleration, and    }
  387.     picbutScaleFastAccel = $03000000; {    Fast Acceleration.          }
  388.     picbutLinear         = 0;         {    Linear (use in structure)   }
  389.     picbutSlowAccel      = 1;         {    Slow (use in structure)     }
  390.     picbutMedAccel       = 2;         {    Medium (use in structure)   }
  391.     picbutFastAccel      = 3;         {    Fast (use in structure)     }
  392.     picbutValueWrap      = $00800000; { Button's range of values 'wrap'}
  393.                                       {   around.                      }
  394.     picbutLeftRightSplit = $00400000; { Left side reduces value, right }
  395.                                       {   increases.                   }
  396.     picbutTopBottomSplit = $00200000; { Top increases value, bottom    }
  397.                                       {   reduces.                     }
  398.     picbutMultiStage     = $00100000; { Button has multiple stages     }
  399.     picbutBigSICN3D      = $00080000; { Create a larger SICN 3D button }
  400.     picbutUsePICTS       = $00040000; { Use PICTs instead of icons     }
  401.     picbutGray4use8      = $00020000; { Use 8-bit color pict on 4-bit  }
  402.                                       {   gray monitor.                }
  403.                                       {Selection Effects…              }
  404.     picbutSelectDarken        = $00010000; { Darken image              }
  405.     picbutSelectDarkenSICN3D  = $00008000; { Darken (and push in) a 3D }
  406.                                            {   SICN icon.              }
  407.     picbutSelectLightenSICN3D = $00004000; { Lighten (and push in) a 3D}
  408.                                            {   SICN icon.              }
  409.     picbutSelectPushedSICN3D  = $00002000; { Same color (and push in) a}
  410.                                            {   3D SICN icon.           }
  411.     picbutSelectAltImage      = $00000400; { Use an alternate image    }
  412.                                            {Disabling Effects…         }
  413.     picbutDimUsingBlackLite   = $00000100; { Overlay Black color using }
  414.                                            {   Lt Gray pattern.        }
  415.     picbutDimUsingWhiteLite   = $00000080; { Overlay White color using }
  416.                                            {   Lt Gray pattern.        }
  417.     picbutDimUsingWhite       = $00000040; { Overlay White color using }
  418.                                            {   Gray pattern.           }
  419.     picbutDimLeaveBorder      = $00000008; { Leave border when applying}
  420.                                            {   the effect.             }
  421.     picbutDimAltImage         = $00000004; { Use an alternate image    }
  422.     picbutDimNoChange         = $00000002; { Button looks the same when}
  423.                                            {   disabled.               }
  424.  
  425. ------------------------------------------------------------------------
  426.